Aminet 18

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 18 / aminetcdnumber181997.iso / Aminet / util / libs / Intoids.lha / Intoids 1.0 / Developer / Docs / Intoids.doc < prev

Wrap

Text File | 1997-02-13 | 40.7 KB | 1,117 lines

TABLE OF CONTENTS intoids.library/--background-- intoids.library/--FileFormat-- intoids.library/--UserCallBackStreamFunction-- intoids.library/AbsoluteIntoid intoids.library/AddIntoids intoids.library/AsciiToIntoid intoids.library/CompareIntoidMagnitudes intoids.library/CompareIntoids intoids.library/CopyIntoid intoids.library/DivideIntoids intoids.library/FreeIntoid intoids.library/GetIntoidsMessage intoids.library/GetLastIntoidErrorMessage intoids.library/IntoidFitsInLong intoids.library/IntoidToAscii intoids.library/IntoidToLong intoids.library/IntoidToPortableIntViaBuffer intoids.library/IntoidToPortableIntViaCallBack intoids.library/LongToIntoid intoids.library/MultiplyIntoids intoids.library/NegateIntoid intoids.library/PortableIntLengthViaBuffer intoids.library/PortableIntLengthViaCallBack intoids.library/PortableIntSizeOfIntoid intoids.library/PortableIntToIntoidViaBuffer intoids.library/PortableIntToIntoidViaCallBack intoids.library/SignOfIntoid intoids.library/SmallIntToIntoid intoids.library/SubtractIntoids intoids.library/--background-- intoids.library/--background-- NAME intoids.library -- Arbitrary precision integer math in 32 bits. FUNCTION This set of subroutines lets other programs easily handle large integer numbers. It is a wrapper around the GNU Integer library (which implements large integers as an array of shorts) that lets you deal with all integers as 32 bit values (small integers are stored as a shifted odd value and larger ones are stored as a pointer to a variation of the GNU large integer). It also supports special values for infinity and not-a-number conditions. Written to support large sized files in the upcoming AGMS virtual file system. INPUTS RecycleMe - most functions that return an Intoid also take a parameter called RecycleMe. Treat it as if it is used in a call to the FreeIntoid function. If RecycleMe isn't NULL then its storage will be recycled to hold the result (or reallocated if it is too small). If RecycleMe is NULL then new memory will be allocated for the function result. If the function fails (returns NULL) then the RecycleMe variable is deallocated. This is here mostly to reduce the number of memory allocations that would otherwise be made. RESULT Intoid values - all functions returning Intoids will return NULL if out of memory or if the number is too big to be represented. Some also return NULL for not-a-number error conditions (like divide by zero). COPYRIGHT Modifications for storing smaller integers in 32 bit values and conversion to an Amiga library copyright (C) 1996 by Alexander G. M. Smith. Original long integer code copyright (C) 1988 Free Software Foundation. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. AUTHOR Modifications for the Amiga library and 32 bit storage implemented by Alexander G. M. Smith, Ottawa Canada, agmsmith@achilles.net, agmsmith@FreeNet.Carleton.ca, agmsmith@bix.com, 71330.3173@compuserve.com, and probably other places in the future. Send mail to all these addresses to find ones which are still valid (list made in November 1996). Original long integer code written by Doug Lea (dl@rocky.oswego.edu). The GNU G++ library's Integer.cc file also has these attributions: Some of the following algorithms are very loosely based on those from MIT C-Scheme bignum.c, which is Copyright (c) 1987 Massachusetts Institute of Technology with other guidance from Knuth, vol. 2 Thanks to the creators of the algorithms. NOTES To compile intoids.library, use the SAS C compiler, version 6.56. Use 32 bit integers, 32 bit longs and 16 bit shorts. Naturally, you can use whatever compiler you want to write code for calling the library (SASC and GNU are supported, and there is an .FD file for making interfaces for other compilers). Here's the SCOPTIONS file I used for making intoids.library: PARAMETERS=REGISTERS NOSTACKCHECK NOCHECKABORT ERRORREXX OPTIMIZE LINK LISTMACROS LISTINCLUDES STRINGSCONST OPTIMIZERINLINELOCAL VERBOSE MAP MAPHUNK MAPSYMBOLS MAPLIB MAPXREFERENCE STRICT LIBRARYCODE OPTIMIZERTIME STRINGSECTION=CODE STARTUP=libinit PROGRAMNAME=intoids.library MAPFILE=Intoids.map PUBSCREEN=Workbench LIBRARYFDFILE=Intoids.fd LIBRARYVERSION=1 LIBRARYREVISION=0 OPTIMIZERCOMPLEXITY=1 OPTIMIZERDEPTH=1 OPTIMIZERRECURDEPTH=0 BUGS Not all the functions from the GNU Integer library were implemented. If you want modulo, power and other functions, either ask me or do it yourself. It's a matter of cutting and pasting the code from GNU's Integer.cc and fixing up a few things to handle Intoids rather than IntReps. SEE ALSO GNU's G++ library Integer.cc file for the original code and yet more arbitrary precision functions. intoids.library/--FileFormat-- intoids.library/--FileFormat-- NAME AGMSPortableIntFormat -- Description of the Portable Integer Format. FUNCTION This binary number format has to handle all values that could be represented by an Intoid and has to be efficient in storage space (so that the AGMS virtual file system databases aren't too large). It also has to be machine independant. To make things simpler for current computer architectures, it is based on a variable quantity of 8 bit bytes (almost all computers can pick out an 8 bit byte from their memory efficiently, few can handle arbitrarily large bit aligned data nicely, particularly in the C language). The general format is: FirstByte, optional size extension bytes, optional data bytes. The size extension byte(s) are located just after FirstByte and just before the actual data bytes. If the first size extension byte is 255 (all 1 bits) then the size value is in two bytes after that (least significant byte comes first), and if those are all 1 bits then the size is in the following 4 bytes, and so on, doubling in length if the previous size extension value is all 1 bits. Don't use an extension of zero, that can cause trouble with some code (extensions of zero are used to signal errors in the Intoids code). The number of optional data bytes is defined by the FirstByte and the optional size extension bytes. Large integers are stored as a positive magnitude (the sign is encoded in FirstByte) in the data bytes. The least significant byte comes first, followed by increasingly more significant bytes. This was done because it is easier to shrink or expand from the end of an array rather than the start of an array when a number gets smaller or larger. The first byte can either be a small integer value (so that things like file name string lengths fit in a byte) or part of a larger integer or a special code. Some numbers can be represented in several different ways, you should be able to read all varieties, and preferably write the shortest one. Here is the encoding for the first byte: $0 to $7F: A small positive integer with value 0 to 127 directly corresponding to treating FirstByte as an 8 bit 2's complement integer. $96 to $FF: A small negative integer with value -106 to -1 directly corresponding to treating FirstByte as an 8 bit 2's complement integer. $80 to $87 A positive number with 1 to 8 bytes of data following the FirstByte. The number of data bytes is (unsigned byte) FirstByte - $7F. No size extension bytes. $88 to $8F A negative number with 1 to 8 bytes of data following the FirstByte. The number of data bytes is (unsigned byte) FirstByte - $87. No size extension bytes. $90 A positive integer. Has a size extension and a data section. The size extension specifies the number of bytes in the data section. $91 A negative integer. Has a size extension and a data section. The size extension specifies the number of bytes in the data section. $92 Signals that an extended special code follows, the size extension bytes specify the special code. There is no data section. Note that we want to avoid a size extension of zero (causes trouble), so the special codes start at 1. $93 to $95 A special code number. The particular one is FirstByte - $92. There is no data section or size extension. The special codes are: 1: Positive integer infinity. 2: Negative integer infinity. 3: Not a number. The NULL pointer of numbers. The quiet kind of not-a-number (doesn't raise error conditions when used). 4: Noisy variety of not-a-number. Generates an error if used in math? Intoids don't support it. Uses FirstByte $92 style encoding. 5+: Future use, uses FirstByte $92 style for encoding. EXAMPLE 00 A positive integer with a value of zero. No size extension or data bytes. F6 A negative integer with a value of -10. No size extension or data bytes. 80 C8 A positive integer with no size extension and 1 ($80 - $7F = 1) data byte. It has a value of +200. 8B 00 CA 9A 3B A negative integer with no size extension and 4 ($8B - $87 = 4) data bytes. It has a value of -$3B9ACA00 = -1000000000. 90 12 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 A positive integer with a size extension of $12 = 18, and 18 data bytes. It has a value of $181716151413121110090807060504030201. 90 FF 23 01 (FF repeated 291 times) A positive integer with a size extension of $123 = 291 (note the first size extension byte is $FF which means see the next two bytes ($23 $01) for the size extension). The data section has 291 bytes of $FF each. This is an integer with a value of 2^2328 - 1. 93 Special code 1, meaning positive infinity. 94 Special code 2, meaning negative infinity. 95 This is special code 3, the code for a quiet not-a-number. 92 04 Special code number 4, error signalling variety of not-a-number. 92 FF 23 01 Special code number $123 = 291. Currently not defined to mean anything (future use). No data section even though it has size extension bytes. 91 FF FF FF 78 56 34 12 01 02 03 [and 305419893 more bytes here] This is a negative integer with $12345678 = 305419896 bytes of number in the data section. Note the way the size extension grew to hold the size of $12345678. Most current computers would have trouble loading this 300 megabyte number into memory, let alone multiplying it with another one. intoids.library/--UserCallBackStreamFunction--/--UserCallBackStreamFunction-- NAME AGMSPortableIntStreamCallBack -- User defined function for stream IO. SYNOPSIS LONG STACKCALL AGMSPortableIntStreamCallBack ( ULONG Operation, APTR Buffer, LONG Amount, APTR UserPntr ); FUNCTION A user defined callback function that is used for reading and writing AGMS Portable Integer numbers from or to a stream. INPUTS Operation - this argument specifies what your function should do: 0: Read data. Fill the buffer with Amount data bytes. Your function returns the amount read, which will be less than the Amount requested if it fails (end of file etc). 1: Seek. Seek relative to the current stream postion by Amount bytes. Amount is negative for seeking backwards, but PortableInt functions will never do that. Returns the position in the stream if known, or just zero when it succeeds, returns -1 if it fails (seek past EOF or before start of file, IO errors). Return -2 if you don't implement seek, and a bunch of reads will be used instead. 2: Write data. Write Amount bytes from the buffer to the stream. Returns the amount written, which will be less than the Amount requested if it fails (IO error etc). N: For other unsupported Operation values please return -2. Buffer - points to a buffer where the read in data is saved or the data to be written is obtained. Amount - used to specify the number of bytes to read, skip over, or write. UserPntr - the same value as passed into the original PortableInt function call. Usually will be a file handle or something similar. RESULT ActualAmount - the function returns the number of bytes actually read or written, or the absolute file position after a seek. NOTES The callback function is called using the C language stack based calling convention. In SAS C this is specified with the __stdargs keywords. BUGS Returned seek position value only good for files up to 2G. SEE ALSO PortIntCallBackOp enum in Intoids.h, STACKCALL macro in Intoids.h. intoids.library/AbsoluteIntoid intoids.library/AbsoluteIntoid NAME AbsoluteIntoid -- Computes absolute value of an Intoid. SYNOPSIS NewIntoid = AbsoluteIntoid( IntegerA, RecycleMe ) D0 D0 D1 Intoid AbsoluteIntoid( Intoid, Intoid ); FUNCTION Computes the absolute value of an Intoid. INPUTS IntegerA - the value you want to get the negative of. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - newly allocated Intoid containing a copy of IntegerA if IntegerA was positive, or the negative of IntegerA if it was originally negative (the negative of a negative is positive), or NULL if out of memory. intoids.library/AddIntoids intoids.library/AddIntoids NAME AddIntoids -- Adds two Intoids. SYNOPSIS NewIntoid = AddIntoids( IntegerA, IntegerB, RecycleMe ) D0 D0 D1 A0 Intoid AddIntoids( Intoid, Intoid, Intoid ); FUNCTION Adds two intoids and returns a new one with the sum. INPUTS IntegerA - one value to be added. IntegerB - the other value to be added. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - newly allocated Intoid with a value of (A + B), or NULL if out of memory. intoids.library/AsciiToIntoid intoids.library/AsciiToIntoid NAME AsciiToIntoid -- Convert an ASCII string to an Intoid. SYNOPSIS New = AsciiToIntoid( Buffer, NextCharacterPntrPntr, Base, RecycleMe ) D0 A0 A1 D0 D1 Intoid AsciiToIntoid( STRPTR, char **, UWORD, Intoid ); FUNCTION Converts a string to a number using the given base, much like the standard C function strtol. It recognizes numbers consisting of some leading space ((spaces or tabs) or international isspace() if locale.library is available), an optional sign, an optional base indicator if Base is zero, and finally a bunch of digits (which can also be the special current language specific strings for infinity or not-a-number). INPUTS Buffer - points to a buffer containing the NUL terminated string to be converted. NextCharacterPntrPntr - points to a user's pointer variable, or NULL if you don't want to use it. The user's pointer variable will be set to point to the character after the last one that was part of the number (or set to NULL if a bad error happened). Base - which number system to use. Base can be from 2 to 36. A Base of 0 can be used for automatic base determination (if the number starts with "0x" then it is treated as base 16, if it starts with "0" then base 8 is used, otherwise it defaults to base 10). RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT New - a newly allocated Intoid with the integer equivalent to the string in Buffer. NULL if out of memory or some other error happens (or if the string says not-a-number). NextCharacterPntrPntr - sets user's pointer to just after the number. NOTES The special strings for infinity and not-a-number are language dependent. If you read a file written in English on a French computer, it won't understand the special infinity values. Instead, you should use the portable binary formatting functions. SEE ALSO GetIntoidsMessage(), MSG_INTOIDS_NOT_A_NUMBER, MSG_INTOIDS_INFINITY. intoids.library/CompareIntoidMagnitudesntoids.library/CompareIntoidMagnitudes NAME CompareIntoidMagnitudes -- Comparison of absolute values. SYNOPSIS Result = CompareIntoidMagnitudes( IntegerA, IntegerB ) D0 D0 D1 LONG CompareIntoidMagnitudes( Intoid, Intoid ); FUNCTION Compares the absolute values of two Intoids, more efficiently than using a subtraction of absolute values. INPUTS IntegerA - one input value. IntegerB - the other input value. RESULT Result - returns a long value that depends on the comparison: -1 for abs(IntegerA) < abs(IntegerB), 0 for abs(IntegerA) == abs(IntegerB), +1 for abs(IntegerA) > abs(IntegerB). SEE ALSO SignOfIntoid(), CompareIntoids(). intoids.library/CompareIntoids intoids.library/CompareIntoids NAME CompareIntoids -- Signed comparison of two Intoid values. SYNOPSIS Result = CompareIntoids( IntegerA, IntegerB ) D0 D0 D1 LONG CompareIntoids( Intoid, Intoid ); FUNCTION Compares the size of two Intoids, more efficiently than using a subtraction. INPUTS IntegerA - one input value. IntegerB - the other input value. RESULT Result - returns a long value that depends on the comparison: -1 for IntegerA < IntegerB, 0 for IntegerA == IntegerB, +1 for IntegerA > IntegerB. SEE ALSO SignOfIntoid(), CompareIntoidMagnitudes(). intoids.library/CopyIntoid intoids.library/CopyIntoid NAME CopyIntoid -- Allocates a copy of an Intoid. SYNOPSIS NewIntoid = CopyIntoid( IntegerA, RecycleMe ) D0 D0 D1 Intoid CopyIntoid( Intoid, Intoid ); FUNCTION Allocates memory (if needed) and fills it with a copy of IntegerA. INPUTS IntegerA - the Integer value you want to copy. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - A copy of IntegerA or NULL if out of memory. intoids.library/DivideIntoids intoids.library/DivideIntoids NAME DivideIntoids -- Computes value of one Intoid divided by another. SYNOPSIS NewIntoid = DivideIntoids( IntegerA, IntegerB, RecycleMe ) D0 D0 D1 A0 Intoid DivideIntoids( Intoid, Intoid, Intoid ); FUNCTION Does division, IntegerA / IntegerB. INPUTS IntegerA - one input value. IntegerB - the other input value. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - newly allocated Intoid containing the value of (IntegerA / IntegerB), or NULL if out of memory or if you divided by zero. intoids.library/FreeIntoid intoids.library/FreeIntoid NAME FreeIntoid -- Deallocates an Intoid. SYNOPSIS FreeIntoid( RecycleMe ) A0 void FreeIntoid( Intoid ); FUNCTION Deallocates memory used by the given Intoid. OK to pass in NULL. Like regular pointers, you shouldn't use the value in RecycleMe any more after calling this function. INPUTS RecycleMe - a previously allocated Intoid or NULL. intoids.library/GetIntoidsMessage intoids.library/GetIntoidsMessage NAME GetIntoidsMessage -- Convert a message number to a localised string. SYNOPSIS YourString = GetIntoidsMessage( StringNumber ) D0 D0 STRPTR GetIntoidsMessage( IntoidStringNumbers ); FUNCTION Returns a pointer to a message which corresponds to the string number, the particular string depends on the user's language preferences. The string is obtained from the Intoids.catalog file if the user's language isn't English. INPUTS StringNumber - an enum from 0 to MSG_INTOIDS_MAX-1 that identifies the message you want the international string for. If you ask for a string that doesn't exist, you will get the string for MSG_INTOIDS_UNKNOWN_MESSAGE. RESULT YourString - a pointer to a read-only string which will be valid for as long as intoids.library is open. SEE ALSO locale.library - docs on how locale stuff works. Intoids.h - the enum of all message numbers. intoids.library/GetLastIntoidErrorMessageds.library/GetLastIntoidErrorMessage NAME GetLastIntoidErrorMessage -- Returns the latest error message. SYNOPSIS MyString = GetLastIntoidErrorMessage( ) D0 STRPTR GetLastIntoidErrorMessage( VOID ); FUNCTION Returns a pointer to the last error message. Maybe be incorrect if you are using multitasking to cause errors (you get the global latest error, not your latest error). Also resets the error message to be the copyright and credits for this library (you get that message if there hasn't been an error since the last call to this function). RESULT MyString - a pointer to a read only string in your favorite language. NOTES The same message was displayed to the user in a system requester, or maybe not if that feature is turned off by the user. intoids.library/IntoidFitsInLong intoids.library/IntoidFitsInLong NAME IntoidFitsInLong -- Tests if an Intoid fits in a long int. SYNOPSIS Boolean = IntoidFitsInLong( IntegerA ) D0 D0 BOOL IntoidFitsInLong( Intoid ); FUNCTION Tests if an Intoid can be represented by an ordinary 32 bit long int. INPUTS IntegerA - any Intoid. RESULT Boolean - TRUE if the Intoid can fit into a long integer. Numbers too big, infinities and not-a-number return FALSE. SEE ALSO IntoidToLong(). intoids.library/IntoidToAscii intoids.library/IntoidToAscii NAME IntoidToAscii -- Converts an Intoid into printable ASCII text. SYNOPSIS RequiredLength = IntoidToAscii( IntegerA, Buffer, BufferLength, Base) D0 A0 A1 D0 D1 LONG IntoidToAscii( Intoid, STRPTR, LONG, UWORD ); FUNCTION Converts the Intoid to a readable string number in the given base. Also can output special strings for not-a-number and infinities, and various error messages if something goes wrong during the conversion. INPUTS IntegerA - any Intoid. Buffer - points to a user provided buffer that will be filled with the NUL terminated string ASCII text equivalent of IntegerA. This variable can be NULL (useful if you just want an estimate of how long the string would be). BufferLength - how many bytes are in Buffer. Can be zero. Base - what number system to use for the conversion. Can be from 2 to 36 (because it uses the 26 lower case letters and '0' to '9' for the output digits). RESULT RequiredLength - returns the number of characters plus one (for the NUL at the end of the string) required to represent the number (may be more than BufferLength). Buffer - filled with the number, or with '*' characters if it isn't big enough to hold the number. NOTES Uses about 1K of the caller's stack space. BUGS Numbers can only be converted if they are less than MAX_INTOID_ASCII_DIGITS long. This is because a reversed number is built up in a buffer this big on the caller's stack (thus you need about 1K of stack when calling this function). If a number is too big, you will get an error message instead of the number. intoids.library/IntoidToLong intoids.library/IntoidToLong NAME IntoidToLong -- Converts an Intoid into a long integer. SYNOPSIS MyLong = IntoidToLong( IntegerA ) D0 D0 LONG IntoidToLong( Intoid ); FUNCTION Converts an Intoid into the closest long integer. INPUTS IntegerA - any Intoid. RESULT MyLong - an ordinary 32 bit long int equal to IntegerA in value, if possible. If IntegerA is too big or too small then you get the largest (0x7FFFFFFF) or smallest (0x80000000) long possible. Plus and minus infinity become largest and smallest longs respectively. Not-a-number becomes zero. SEE ALSO IntoidFitsInLong(). intoids.library/IntoidToPortableIntViaBufferrary/IntoidToPortableIntViaBuffer NAME IntoidToPortableIntViaBuffer -- Converts Intoid to portable int. SYNOPSIS Success = IntoidToPortableIntViaBuffer ( AnIntoid, BytesWrittenPntr, Buffer, BufferSize ) D0 D0 A0 A1 D1 BOOL IntoidToPortableIntViaBuffer( Intoid, ULONG *, APTR, ULONG ); FUNCTION Writes the AGMS Portable Integer binary format equivalent of the Intoid (big integer) to a buffer. INPUTS AnIntoid - the arbitrarily big integer to be converted. BytesWrittenPntr - points to a ULONG that will be set to the number of bytes written, specify NULL if you aren't using this feature. Buffer - points to an area of memory where the portable integer will be written to. BufferSize - amount of space in the buffer. Has to be at least enough for the entire portable integer, or you get a partial portable integer in the buffer and BytesWritten equal to BufferSize. RESULT Success - returns TRUE (1) if successful, FALSE (0) if it fails. BytesWrittenPntr - the pointed to ULONG is set to the number of bytes actually written. If you have an IO error then this will be less than the actual size (see PortableIntSizeOfIntoid()) for the number. SEE ALSO PortableIntSizeOfIntoid(), IntoidToPortableIntViaCallBack(). intoids.library/IntoidToPortableIntViaCallBack/IntoidToPortableIntViaCallBack NAME IntoidToPortableIntViaCallBack -- Converts Intoid to portable int. SYNOPSIS Success = IntoidToPortableIntViaCallBack ( AnIntoid, BytesWrittenPntr, CallBack, UserPntr) D0 D0 A0 D1 A1 BOOL IntoidToPortableIntViaCallBack ( Intoid, ULONG *, PortIntCallBackPntr, APTR ); FUNCTION Writes the AGMS Portable Integer binary format equivalent of the Intoid to a stream using a callback function. Also tests to see if your compiler can handle 30 letter function names :-). INPUTS AnIntoid - the Intoid big integer to be converted. BytesWrittenPntr - points to a ULONG that will be set to the number of bytes written, specify NULL if you aren't using this feature. CallBack - a user provided function that handles the input stream, see the intoids.library/AGMSPortableIntStreamCallBack entry in these autodocs for details. UserPntr - Any pointer sized value you want. This value will be passed to your callback function. Typically used for file handles. RESULT Success - returns TRUE (1) if successful, FALSE (0) if it fails. BytesWrittenPntr - the pointed to ULONG is set to the number of bytes actually written. If you have an IO error then this will be less than the actual size (see PortableIntSizeOfIntoid()) for the number. SEE ALSO PortableIntSizeOfIntoid(), IntoidToPortableIntViaBuffer(), AGMSPortableIntStreamCallBack. intoids.library/LongToIntoid intoids.library/LongToIntoid NAME LongToIntoid -- Converts a long int to an Intoid. SYNOPSIS NewIntoid = LongToIntoid( LongA, RecycleMe ) D0 D0 A0 Intoid LongToIntoid( LONG, Intoid ); FUNCTION Converts a 32 bit long int into an Intoid. INPUTS LongA - the integer you want to convert. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - a newly allocated Intoid with value equal to LongA. NULL if out of memory. SEE ALSO SmallIntToIntoid(). intoids.library/MultiplyIntoids intoids.library/MultiplyIntoids NAME MultiplyIntoids -- Computes value of one Intoid times another. SYNOPSIS NewIntoid = MultiplyIntoids( IntegerA, IntegerB, RecycleMe ) D0 D0 D1 A0 Intoid MultiplyIntoids( Intoid, Intoid, Intoid ); FUNCTION Does multiplication, IntegerA * IntegerB. INPUTS IntegerA - one input value. IntegerB - the other input value. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - newly allocated Intoid containing the value of (IntegerA * IntegerB), or NULL if out of memory. intoids.library/NegateIntoid intoids.library/NegateIntoid NAME NegateIntoid -- Returns the negative of an intoid. SYNOPSIS NewIntoid = NegateIntoid( IntegerA, RecycleMe ) D0 D0 D1 Intoid NegateIntoid( Intoid, Intoid ); FUNCTION Computes (0 - IntegerA). INPUTS IntegerA - the value you want to get the negative of. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - newly allocated Intoid containing (0 - IntegerA), or NULL if out of memory. intoids.library/PortableIntLengthViaBuffer.library/PortableIntLengthViaBuffer NAME PortableIntLengthViaBuffer -- Gets byte size of portable integer. SYNOPSIS Length = PortableIntLengthViaBuffer( Buffer, BufferSize ) D0 A0 D1 ULONG PortableIntLengthViaBuffer( APTR, ULONG ); FUNCTION Finds the length in bytes of an AGMS Portable Integer in a buffer. INPUTS Buffer - points to an area of memory containing the portable integer. BufferSize - amount of data in the buffer. RESULT Length - returns the length or zero if something went wrong (hit end of buffer before number completed, unsupported number kind or bad number format). Length includes the header size. BUGS Doesn't work for numbers that take more than 2 Gigabytes of storage space (garbage results in that case - but then that would be a very big number that nobody would ever use, well maybe we could return an Intoid instead of a ULONG :-). SEE ALSO PortableIntLengthViaCallBack(). intoids.library/PortableIntLengthViaCallBackrary/PortableIntLengthViaCallBack NAME PortableIntLengthViaCallBack -- Gets byte size of portable integer. SYNOPSIS Length = PortableIntLengthViaCallBack( CallBack, UserPntr ) D0 D0 D1 ULONG PortableIntLengthViaCallBack( PortIntCallBackPntr, APTR ); FUNCTION Finds the length in bytes of an AGMS Portable Integer and skips over it. INPUTS CallBack - a user provided function that handles the input stream, see the intoids.library/AGMSPortableIntStreamCallBack entry in these autodocs for details. UserPntr - Any pointer sized value you want. This value will be passed to your callback function. Typically used for file handles. RESULT Length - returns the length or zero if something went wrong (read error or unsupported number kind or bad number format, in which case an unknown number of bytes will have been read). Length includes the header size. NOTES As a side effect, it has read all the bytes in the number. You can use this function to skip over a number (it seeks past the number contents for big numbers). BUGS Doesn't work for numbers that take more than 2 Gigabytes of storage space (garbage results in that case, and unpredictable number of bytes read in that case too - but then that would be a very big number that nobody would ever use, well except when trying to foil nanotechnology based decryption systems :-). SEE ALSO PortableIntLengthViaBuffer(), AGMSPortableIntStreamCallBack. intoids.library/PortableIntSizeOfIntoidntoids.library/PortableIntSizeOfIntoid NAME PortableIntSizeOfIntoid -- Find Intoid size in portable int format. SYNOPSIS Length = PortableIntSizeOfIntoid( AnIntoid ) D0 D0 ULONG PortableIntSizeOfIntoid( Intoid ); FUNCTION Finds the byte size of an Intoid when expressed in AGMS Portable Integer format. INPUTS AnIntoid - the big integer you want to find the formatted size of. RESULT Length - the number of bytes it would take for the AGMS Portable Integer binary format equivalent of AnIntoid. intoids.library/PortableIntToIntoidViaBufferrary/PortableIntToIntoidViaBuffer NAME PortableIntToIntoidViaBuffer -- Converts portable int to Intoid. SYNOPSIS NewIntoid = PortableIntToIntoidViaBuffer ( Buffer, BufferSize, AmountReadPntr, RecycleMe ) D0 A0 D0 A1 D1 Intoid PortableIntToIntoidViaBuffer( APTR, ULONG, ULONG *, Intoid ); FUNCTION Reads an arbitrarily long integer in AGMS Portable Integer format from a buffer and returns the Intoid equivalent. INPUTS Buffer - points to an area of memory containing the portable integer. BufferSize - amount of data in the buffer. Has to be at least enough for the entire portable integer, or you get NULL returned. AmountReadPntr - points to a long variable where the number of bytes read will be placed. Set to NULL if you don't want to use this feature. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - an Intoid equivalent to the number, or NULL if it fails, also NULL if the number is not-a-number. AmountReadPntr - pointed to variable is updated with the number of bytes that were actually read, will be from zero to BufferSize. BUGS Doesn't work with numbers over 2G in storage space, but they won't fit in an Intoid anyways (128K bytes max in an Intoid) or even in most system's memory. SEE ALSO PortableIntToIntoidViaCallBack(). intoids.library/PortableIntToIntoidViaCallBack/PortableIntToIntoidViaCallBack NAME PortableIntToIntoidViaCallBack -- Converts portable int to Intoid. SYNOPSIS NewIntoid = PortableIntToIntoidViaCallBack ( CallBack, UserPntr, AmountReadPntr, RecycleMe ) D0 A0 D0 A1 D1 Intoid PortableIntToIntoidViaCallBack ( PortIntCallBackPntr, APTR, ULONG *, Intoid ); FUNCTION Reads an arbitrarily long integer in AGMS Portable Integer format from some input stream and returns the result as an Intoid. INPUTS CallBack - a user provided function that handles the input stream, see the intoids.library/AGMSPortableIntStreamCallBack entry in these autodocs for details. UserPntr - Any pointer sized value you want. This value will be passed to your callback function. Typically used for file handles. AmountReadPntr - points to a long variable where the number of bytes read will be placed. Set to NULL if you don't want to use this feature. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - an Intoid equivalent to the number, or NULL if it fails, also NULL if the number is not-a-number. AmountReadPntr - pointed to variable is updated with the number of bytes that were actually read. NOTES Advances the stream to just past the number, if it succeded. BUGS Doesn't work with numbers over 2G in storage space, but they won't fit in an Intoid anyways (128K bytes max in an Intoid). SEE ALSO PortableIntToIntoidViaBuffer(), AGMSPortableIntStreamCallBack. intoids.library/SignOfIntoid intoids.library/SignOfIntoid NAME SignOfIntoid -- Returns -1, 0 or +1 depending on Intoid's sign. SYNOPSIS MySign = SignOfIntoid( IntegerA ) D0 D0 LONG SignOfIntoid( Intoid ); FUNCTION Fast way of finding the sign of any Intoid. INPUTS IntegerA - any Intoid you want to find the sign of. RESULT MySign - reflects the sign of IntegerA in a LONG value. Returns -1 for negative integers (includes negative infinity), 0 for zero and non-numbers, 1 for positive integers (and +infinity). SEE ALSO CompareIntoids(), CompareIntoidMagnitudes(). intoids.library/SmallIntToIntoid intoids.library/SmallIntToIntoid NAME SmallIntToIntoid -- Macro to convert a small value int to an Intoid. SYNOPSIS MyIntoid = SmallIntToIntoid( ANumber ) Intoid SmallIntToIntoid( int ); FUNCTION Converts a short integer or char (unsigned or signed) to an Intoid. Will also work for long integers if they aren't larger than 0x3FFFFFFF in absolute value. Use LongToIntoid to properly handle larger longs. INPUTS ANumber - some signed or unsigned char, int or long. RESULT MyIntoid - the Intoid equivalent, as a small integer form Intoid. Never returns NULL since it doesn't do memory allocation. NOTES Only works for integers with absolute value of 0x3FFFFFFF or less. Defined in <libraries/Intoids.h>. SEE ALSO LongToIntoid(). intoids.library/SubtractIntoids intoids.library/SubtractIntoids NAME SubtractIntoids -- Computes value of one Intoid minus another. SYNOPSIS NewIntoid = SubtractIntoids( IntegerA, IntegerB, RecycleMe ) D0 D0 D1 A0 Intoid SubtractIntoids( Intoid, Intoid, Intoid ); FUNCTION Does subtraction, IntegerA - IntegerB. INPUTS IntegerA - one input value. IntegerB - the other input value. RecycleMe - an old Intoid you want to deallocate, or NULL. RESULT NewIntoid - newly allocated Intoid containing the value of (IntegerA - IntegerB), or NULL if out of memory.